Cream of the Crop 26

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 26 / Cream of the Crop 26.iso / editor / txtab707.zip / TXTABLE.DOC < prev next >

Wrap

Text File | 1997-07-31 | 28KB | 584 lines

TXTABLE.DOC 1 Jul 31, 1997 WIN95 AND WINNT NOTICE: As with most DOS-based utilities, this program doesn't understand the weird subdirectories, long filenames, invalid characters that are possible under Windows 95 and Windows/NT. Both operating systems alias long filenames into names like MYFILE~1.TXT and you will need to specify the aliased versions of file names to process them. Under some file structure systems in NT, the program may not work at all. This program creates tables from an ASCII text input file. Easier to maintain than most word processing tables, the program automatically handles alignment and such. Features: * Creates tables which can be (at this point) up to 10 columns wide. * Automatically sets table column widths but you can override this. * Allows flexibility in terms of alignment, borders, titles, and page lengths. * You can either use a straight ASCII text input file (typically one record per cell) or else a pseudo-HTML input file * If you use the optional embedded HTML stuff, you can have more than one table per input file. * Pressing escape stops the program early. The TXTABLE.EXE input file: TXTABLE.EXE works off an ASCII text input file which basically tells it what goes in each cell. This file can be created and maintained by hand. (A sample file, TXTABLE2.SAM, should have been included in the ZIP file. It's used as the basis of the example shown below. Feel free to try it out using "TXTABLE TXTABLE2.SAM".) Tables can be indicated in this file in one of two ways. The first is a method which doesn't use HTML commands and basically expects one cell of data per line on input. The second method is based on a limited version of the HTML coding for tables. You will notice that the sample file actually mixes the two techniques in the same file. If this is done, the HTML-based table(s) must appear after the one-line/one-cell model. TXTABLE.DOC 2 Jul 31, 1997 Using format one (non-HTML): Each record in the input file is the contents of a single cell. Long lines are automatically wrapped on output by the program. For example, if you have a table that looks like this: ╔═════════════╦══════════════════╤════════════════════════════════════════════╗ ║ Character ║ Actor/Actress │ Viewpoint ║ ╠═════════════╬══════════════════╪════════════════════════════════════════════╣ ║ Fox Mulder ║ David Duchovny │ Searching for the truth about his sister. ║ ║ ║ │ Conspiracy under every rock. ║ ╟─────────────╫──────────────────┼────────────────────────────────────────────╢ ║ Dana Scully ║ Gillian Anderson │ Science is god. However, strong religious ║ ║ ║ │ beliefs provide second foundation. ║ ╚═════════════╩══════════════════╧════════════════════════════════════════════╝ (This table was generated by the TXTABLE command.) The input file would consist of the nine cells shown above, in the order they are shown. In this case, the input file was the following: Character Actor/Actress Viewpoint Fox Mulder David Duchovny Searching for the truth about his sister. Conspiracy under every rock. Dana Scully Gillian Anderson Science is god. However, strong religious beliefs provide second foundation. Leading spaces are removed by the program for data lines. You can embed comment lines within the input file. Comments are any lines that begin with a colon (":"), semicolon (";"), or slash-asterisk pair ("/*"). These special characters have to begin in column 1. The typical use for comments would be to indicate where table lines begin and what parameters are suggested for this table. For example, a commented input file for this example might be the following: /* TXTABLE2.SAM Character Actor/Actress Viewpoint /* Fox Mulder David Duchovny Searching for the truth about his sister. Conspiracy under every rock. /* Dana Scully Gillian Anderson Science is god. However, strong religious beliefs provide second foundation. One advantage of this approach is that it makes it very easy to move rows around, something which I could never figure out how to do in WordPerfect. A blank line means an empty cell. TXTABLE.DOC 3 Jul 31, 1997 The cell contents can include embedded decimal and hexadecimal strings (including space representations) if desired (see BRUCEHEX.DOC file). If you want to force a new line within a cell (for example, "Actor/" and then have "Actress" on the next line), include the representation of a carriage return/linefeed within the line. For example: Actor/\013\010Actress. If you have a very long cell, you can split the line in your input file into multiple lines. To do this, end the line(s) to be continued with the continuation indicator, which initially defaults to "__". For example, This cell consists of a number of words__ so it's been split into multiple lines to make it easier__ to read in the input file. Leading spaces are ignored by the program (except for comments) and it's much easier to read the lines if you indent the continued lines. Line continuations in the input file has no bearing on where the cells will be wrapped in the final table. That's based exclusively on cell widths and the \013\010 indicators. Note that the program automatically adds one space when it joins the lines unless a space is already there. So the above example will have the cell shown based on "words so" and "easier to". Parts of a table and their alignment: Each table consists of a header section (the first line of cells) and a stub (the left-most column of cells). The contents of the cells within each of these sections can be positioned independently from the body of the table. By default, the contents of the headers are centered, then the stubs are flush left, and then body of the table is also flush left. The uppermost left cell is considered to be part of the header, not the stub. Numeric values are positioned totally independent of everything else. By default, they are positioned flush right. At this point, the program doesn't support decimal alignment so just make sure you have the same number of decimal places for every cell in the column. In addition, you can have an optional title in your table. The title can be as long as you want it; it will be automatically wrapped and centered based on your page width. Note that the only way to have a title is to embed it in your input file. This is explained shortly in the "Specifying parameters" section. TXTABLE.DOC 4 Jul 31, 1997 Using format two (HTML based): The second format for the input file is based on the HTML standard. Having said this, it does *not* the HTML standard; just a subset of it. HTML uses indicators enclosed in "<..>" characters to indicate what's to happen. Unlike the HTMSTRIP command (also released by freeware by this author), TXTABLE only supports certain HTML codes: <BR> Line is to be split at this point <CAPTION>...</CAPTION> Title of table (<TITLE>...</TITLE> works too) <TABLE>...</TABLE> Table definition <TD>...</TD> Table cell data contents <TH>...</TH> Table header data contents <HR> Horizontal rule is to appear here <TITLE>...</TITLE> Title of table (<CAPTION>...</CAPTION> works too) <TR>...</TR> Table row <VERBATIM>...</VERBATIM> Block which follows appears outside of a table block and is to be printed verbatim. A typical table looks like the following: <TABLE> <CAPTION>Main exports by country</CAPTION> <TR><TH>Table stub</TH><TH>Col 1</TH><TH>Col 2</TH></TR> <TR><TD>China</TD> <TD>Textiles</TD> <TD>Apparel</TD></TR> <TR><TD>Japan</TD> <TD>Automobiles</TD> <TD>Electronics</TD></TR> </TABLE> This input file would result in the following output: Main exports by country ╔════════════╦═════════════╤═════════════╗ ║ Table stub ║ Col 1 │ Col 2 ║ ╠════════════╬═════════════╪═════════════╣ ║ China ║ Textiles │ Apparel ║ ╟────────────╫─────────────┼─────────────╢ ║ Japan ║ Automobiles │ Electronics ║ ╚════════════╩═════════════╧═════════════╝ Under the HTML coding conventions, the only forced line breaks are done using the <BR> option or some other HTML command which forces a new row (for example, <TH> or <TITLE>). The <TD ...> and <TH ...> statements can include alignment statements which override the default alignment for that column. These appear like "<TD ALIGN=RIGHT>". Valid ALIGN= values are RIGHT, LEFT, CENTER, or JUSTIFY. TXTABLE.DOC 5 Jul 31, 1997 You can also embed ROWSPAN=n and COLSPAN=n statements in your <TD> and <TR> specifications. These tell the program that the value of the cell extends to the right or down for a certain number of rows or columns. For example: <table> <tr><td colspan=2>1(1)<td>1(2)<td>1(3) <tr><td rowspan=2>2(1)<td>2(2)<td>2(3)<td>2(4) <tr><td>3(1)<td>3(2)<td>3(3) </table> Generates this table: ╔══════╦══════╤══════╤══════╗ ║ 1(1) ║ │ 1(2) │ 1(3) ║ ╠══════╬══════╪══════╪══════╣ ║ 2(1) ║ 2(2) │ 2(3) │ 2(4) ║ ╟──────╫──────┼──────┼──────╢ ║ ║ 3(1) │ 3(2) │ 3(3) ║ ╚══════╩══════╧══════╧══════╝ Unexpected HTML commands are ignored by TXTABLE. Unlike with real HTML commands, TXTABLE expects your HTML commands to begin and end on the same line. TXTABLE.DOC 6 Jul 31, 1997 Column widths: Column widths are set automatically by the program. You can override any of the width settings that you'd like. By default, the program processes your input twice. The first time, it scans for maximum column widths. As far as the program is concerned, the width of the column includes all of the following: * The character(s) after the delimiter that starts the cell (the number of characters being set by /BUFF=n but it defaults to just 1), * The actual text to be stuffed into that cell, * The character(s) before the delimiter that ends the cell (again, /BUFF=n), * The cell delimiter itself (always one character), and * For the first cell only, the very first cell delimiter character. In the example shown above, /BUFF=1 was left by default. The longest string in the first column of cells (the stub) is the string "Dana Scully" which is 11 characters. So the maximum required width for the first column is 1+11+1+1+1 or 15. The second column's longest string is "Gillian Anderson" (must have been when she was pregnant) which is 16 characters in length. So the maximum required width for the secon column is 1+16+1+1+0 or 19. The third column is some big number like 80. The program looks at your specified width for the table, divides it by the number of columns in the table, and figures the average column width. If the maximum width for the column is less than or equal to the average, the program sets the column width to be this maximum. In our example, the default table width of 80 is in effect and there are three columns so the average column width is 27 (80 divided by 3) or so. Since they're smaller than the average, the program sets the width of column 1 and column 2 to be 15 and 19 respectively. The program looks to see if there are any remaining columns. If yes, their width is set to be the remaining width divided by the number of columns affected. In our case, there are 80-15-19 or 46 characters left and one column so the width of the third column is set to be 46 characters and some of the lines of text have to be wrapped accordingly. If the automatic width detection discovers that the specified table width is too big, the program will typically adjust the maximum table width. For example, if you have 3 columns and they're all like 10 characters, the table width will be shrunk appropriately. The page width, however, will stay as it was so the table will appear centered within the given page width. You can adjust any of the widths if you'd like. This is done using the "/{+n}{-n}{@n}..." parameter. For each column in sequence, you can specify one of the following: "+n" says to add "n" characters to the initial width. "-n" says to subtract "n" characters from the initial width. "@n" says to make that column exactly "n" characters in width. TXTABLE.DOC 7 Jul 31, 1997 In our example, the column widths ended up being /@15@19@46. If you wanted to, you could expand the last column and shrink the first one by saying "/-2+0+2" or by using some combination of "@n" specifications to do the same thing. If your adjustments cause the table width to expand or contract, the /WIDTH=n (and /PAGEW=n if necessary) specifications will change appropriately. Except in rather bizarre cases, the default system column settings should be more than adequate. Specifying parameters: Parameters for this program can be set in the following ways. The last setting encountered always wins: - Read from an *.INI file (see BRUCEINI.DOC file), - Through the use of an environmental variable (SET TXTABLE=whatever), or - From the command line (see "Syntax" below) In addition, the TXTABLE.EXE program allows you embed commands within the input file itself. This makes it easier to keep table-specific parameters with the input file. The embedded commands have to begin with "/=" in column one of the input file. Any statement which begins with "/" is processed like a regular parameter. For example: /*TACSCHED.TST /=/7 /border=d /@10@10@10@10@10@10@10 Time (The line which begins with "/*" is just a comment line.) You can have as many "/=" lines as you'd like and they can have multiple options on them. As always, the last parameter encountered wins. In addition to embedding regular commands, you can also specify a table title by putting it on a "/=" line. Any "/=" line that doesn't start with a "/" parameter is, in fact, presumed to be a title. Titles can continue to multiple lines if desired (you don't need the line continuation string to do this) but each line must begin with "/=". For example: /=Return on interest rates based on some stupid formula that /=my boss wants but it must be one that no one seriously /=uses any more. If you'd like to force wrapping, you can embed \013\010 sequences as desired. You can also include The title can include other embedded decimal and hexadecimal strings (including space representations) if desired (see BRUCEHEX.DOC file). Titles that appear on page two or afterward will automatically end with "(cont)" so you'll know it's a continued table. TXTABLE.DOC 8 Jul 31, 1997 Syntax: TXTABLE [ infile ] [ outfile ] [ /n ] [ /EXT=.xxx ] [ /BORDER=c ] [ /ALIGN=c ] [ /ALIGNH=c ] [ /ALIGNN=c ] [ /ALIGNS=c ] [ /RULE=s ] [ /WIDTH=n ] [ /PAGE=n ] [ /PAGEW=n ] [ /FORCE ] [ /EJECT ] [ /BUFF=n ] [ /CONT=s ] [ /{+n}{-n}{@n}... ] [ /DEBUG ] [ /Tpath ] [ /initfile | /-I ] [ /-ENV ] [ /? ] [ /?&H ] where: "infile" is the name of the input file to process. See example above. The program will prompt for an infile name if none is provided. "outfile" is the name of the output file to create. Is overwritten if it exists already. If no output file name is provided, the routine will use the infile and provide an extension of *.TAB. (The default .TAB extension can be overridden using the /EXT=.xxx parameter.) "/n" tells the program how many cells across the table consists of. This is a required parameter if you're not using pseudo-HTML input files. "/EXT=.xxx" allows you to specify a different default file extension for the output file. This parameter only matters if you do not explicitly specify an output file name. The default value is "/EXT=.TAB". "/BORDER=c" specifies the type of border to use. The possible choices for "c" are: D -- double line S -- single line T -- text character line B -- blanks (spaces) N -- none DV -- double line is used for vertical borders, lines are skipped in horizontal rows within the table itself SV -- same as DV except single line TV -- same as DV except text lines Examples of the various border types: <D>ouble <S>ingle <T>ext <B>lank <N>one ╔═══╦═══╤═══╗ ┌───┬───┬───┐ +---+---+---+ ║ 1 ║ 2 │ 3 ║ │ 1 │ 2 │ 3 │ | 1 | 2 | 3 | 1 2 3 1 2 3 ╠═══╬═══╪═══╣ ├───┼───┼───┤ +---+---+---+ 4 5 6 ║ 4 ║ 5 │ 6 ║ │ 4 │ 5 │ 6 │ | 4 | 5 | 6 | 4 5 6 7 8 9 ╟───╫───┼───╢ ├───┼───┼───┤ +---+---+---+ ║ 7 ║ 8 │ 9 ║ │ 7 │ 8 │ 9 │ | 7 | 8 | 9 | 7 8 9 ╚═══╩═══╧═══╝ └───┴───┴───┘ +---+---+---+ <DV> <SV> <TV> ╔═══╦═══╤═══╗ ┌───┬───┬───┐ +---+---+---+ ║ 1 ║ 2 │ 3 ║ │ 1 │ 2 │ 3 │ | 1 | 2 | 3 | ╠═══╬═══╪═══╣ ├───┼───┼───┤ +---+---+---+ ║ 4 ║ 5 │ 6 ║ │ 4 │ 5 │ 6 │ | 4 | 5 | 6 | ║ 7 ║ 8 │ 9 ║ │ 7 │ 8 │ 9 │ | 7 | 8 | 9 | ╚═══╩═══╧═══╝ └───┴───┴───┘ +---+---+---+ TXTABLE.DOC 9 Jul 31, 1997 "/ALIGN=c" specifies how to align the contents of the cells that are not either header or stub cells. In the <T>ext example above, /ALIGN=c would affect cells 5, 6, 8, and 9. Possible values for "c" are R (flush right), L (flush left), J (justify), and C (center). The default is /ALIGN=L. The positioning of any numeric cells is overridden by the /ALIGNN=c parameter. "/ALIGNH=c" specifies how to align the contents of the cells that are part of the first row of cells, called the header. In the <T>ext example above, /ALIGNH=c would affect cells 1 to 3. Possible values for "c" are R (flush right), L (flush left), J (justify), and C (center). The default is /ALIGN=C. The positioning of any numeric cells is overridden by the /ALIGNN=c parameter. "/ALIGNN=c" specifies how to align the contents of cells that are entirely numeric. This specification overrides any other alignment specifications. Possible values for "c" are R (flush right), L (flush left), and C (center). The default in /ALIGNN=R. "/ALIGNS=c" specifies how to align the contents of the cells that are part of the leftmost column of cells, called the stub. The very first cell (cell 1 above), is part of the header, not the stub. In the <T>ext example above, /ALIGNS=c would affect cells 4 and 7. Possible values for "c" are R (flush right), L (flush left), J (justify), and C (center). The default is /ALIGN=L. The positioning of any numeric cells is overridden by the /ALIGNN=c parameter. "/RULE=s" specifies that a string is to be repeated the width of the line. This is used to separate sections. The string can be a single character (like "/RULE=-"), multiple characters (like "/RULE="- ""), it can contain decimal and hexadecimal characters (like "/RULE=\066\097\116"--see BRUCEHEX.DOC), it can be "/RULE=NULL" (which typically results in a blank line), or just simply "/RULE" (which is the same thing as "/RULE=-" if /BORDER=T and "RULE=\196" if /BORDER=S or /BORDER=D). Personally, if your printer supports IBM graphics characters, I find "/RULE=\196" to be the most pleasing of the rule lines. "/WIDTH=n" specifies the desired table width. This determines wrapping long lines and such. Can be reset automatically by the program if your data warrants it. Initially defaults to /WIDTH=80. "/PAGE=n" specifies how long each page is. This will cause the program to judge whether the contents of the current line of cells will fit on the current page. If not, the program will do all of the following steps: * print a blank line, * print an optional page eject (if /EJECT in effect), * reprint any table titles (see "Specifying parameters" above), * repeat the headers over again, and * then produce the next cells. No page is required and in fact the default for this option is /PAGE=0 which turns off any page length adjusting. Doing the adjusting forces the program to store cells in memory and may cause errors if your table exceeds the array bounds that were set for this. The current maximum is 10 lines for the header and 50 lines for any single non-header row. If you do get errors, just use /PAGE=0 and redo it. TXTABLE.DOC 10 Jul 31, 1997 "/PAGEW=n" specifies what the page width is. If no page width is specified, the program will use the /WIDTH=n parameter instead. If the page is wider than the table, the program will center the table within the page. "/FORCE" says that the specified width must be adhered to. The only exception to this is that tables may force a width expansion if the cells simply can't fit on the page otherwise. Using /FORCE means that some words in tables may get split up if the entire word can't fit in the computed cell width. The latter is especially a problem if there are lots of cell columns in a table; there isn't much room for the actual data when the cells themselves take up so much space. Initially defaults to "/-FORCE". "/-FORCE" says that the desired widths can be ignored if table cells would look more natural without it. This is initially the default. "/EJECT" says to put a page eject character (decimal 12) between pages in the table. This is initially the default. You can specify "/-EJECT" if you want to turn them off. See also "/PAGE=n" parameter. "/-EJECT" says to put nothing (including the standard decimal 12 eject characters) between pages in the table. Initially defaults to "/EJECT". "/BUFF=n" specifies how many spaces to position on either side of the vertical bars in the tables. Defaults to /BUFF=1. "/CONT=s" specifies that the contents of lines that end with the specified string indicate that the contents of the cell continues on the next line. This allows you to put fairly long cells in your table without killing your text editor. Note that this does not indicate joined cells in the final table; just that the text of a single cell is huge. A space is presumed before the continuation string whether it's present or not. For ease of reading, you might want to begin the continued lines with one or more spaces. Defaults to /CONT=__ "/{+n}{-n}{@n}..." allows you to adjust the widths of the columns. See the "Column widths" description above. "/DEBUG" is mainly used for testing purposes. It shows the first 80 characters of the table to you on the screen in addition to writing it to your outfile. This allows you to see results of each parameter more easily and make adjustments as necessary. "/Tpath" specifies where to write the temporary files that the routine needs. Examples are "/TC:" and "/TC:\TEMP". If not specified, the routine writes to the following in sequence: - the value of any TEMP, then TMP, environmental variable - C:\TEMP - C:\ "/Iinitfile" says to read an initialization file with the file name "initfile". The file specification *must* contain a period. Initfiles are described in the BRUCEINI.DOC file. Initially defaults to "/ITXTABLE.INI". "/-I" (or "/INULL") says to skip loading the initialization file. TXTABLE.DOC 11 Jul 31, 1997 "/ENV" says to look for %var% occurrences in the command line and try to resolve any apparent environmental variable references. See BRUCEINI.DOC for more information. This is initially the default. "/-ENV" says to skip resolving apparent %var% occurrences in the command line. Initially defaults to "/ENV". "/?" or "/HELP" or "HELP" shows you the syntax for the command. "/?&H" gives you a hexadecimal and decimal conversion table. Return codes: TXTABLE returns the following ERRORLEVEL codes: 0 = no problems 253 = escape pressed 254 = input file not found 255 = syntax problems, or /? requested Author: This program was written by Bruce Guthrie of Wayne Software. It is free for use and redistribution provided relevant documentation is kept with the program, no changes are made to the program or documentation, and it is not bundled with commercial programs or charged for separately. People who need to bundle it in for-sale packages must pay a $50 registration fee to "Wayne Software" at the following address. Additional information about this and other Wayne Software programs can be found in the file BRUCE.DOC which should be included in the original ZIP file. The recent change history for this and the other programs is provided in the HISTORY.ymm file which should be in the same ZIP file where "y" is replaced by the last digit of the year and "mm" is the two digit month of the release; HISTORY.611 came out in November 1996. This same naming convention is used in naming the ZIP file (TXTABymm.ZIP) that this program was included in. Comments and suggestions can also be sent to: Bruce Guthrie Wayne Software 113 Sheffield St. Silver Spring, MD 20910 e-mail: WayneSof@erols.com fax: (301) 588-8986 http://www.geocities.com/SiliconValley/Lakes/2414 Please provide an Internet e-mail address on all correspondence.